<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>

    <title>gmconvert README</title>

<style type="text/css">

body {
   font-family: "Lucida Grande", sans-serif;
   font-size: 12pt;
   background:#E6E6E6;
}

a {
    color:blue;
}

h1 {
    font-size:16px;
}

h2 {
    margin-left:10px;
}

h3 {
    margin-left:20px;
}

h4 {
    margin-left:30px;
}

h5 {
    margin-left:40px
}

p {
    margin-left:40px;
}

</style>
</head>
<body>
<h1 id="readme_gmconvert_v_031_copyright_c_2005_2006_brant_c_faircloth">README GMCONVERT v 0.31; Copyright (c) 2005-2006, Brant C. Faircloth</h1>

<h2 id="disclaimer">Disclaimer</h2>

<p>GeneMapper(TM) is a registered trademark of Applera Corporation and its subsidiaries in the U.S. and other countries.</p>

<p>I am in no way associated with Applera, Perkin-Elmer, Applied Biosystems, etc.  I wrote this program to help myself and those in my group work a bit faster.  I thought it might help others.</p>

<h2 id="about_this_program">About this program</h2>

<p>This program is mean to convert files exported by Applied Biosystem's GeneMapper(TM) software to a format that is more useful.  It essentially re-arrays the data from row to column format.  Pretty much every program i have used for analysis demands the data be in column format of some sort.</p>

<p>The program is distributed as executables for both OS X and Windows (XP).  These both have a simple GUI allowing user interaction.  Neither <em>require</em> that python or wxpython (the windowing system) be installed as they are bundled within the application. </p>

<p>There is also a command-line version (gmconvert_command) that should be supported on all operating systems supporting Python and with Python installed.  My machine runs python 2.4.2 at the moment, so you should have at least that version.  If you do not, things may work strangely.</p>

<h2 id="caveats">Caveats</h2>

<p>Generally, I haven't found too many.  However, you should be aware that your markers must have consistent names if they are placed in different panels.  For example, if you have 'Primer15' in one panel and 'primer15' in another and these are actually the same primer, then you are going to have some problems.  The main reason is that the program is case sensitive, so the previous examples are NOT the same.  So, if you run your exported file with this sort of thing in there, then you will get separate results for 'Primer15' and 'primer15'.  Bummer.  This is easily remedied by ensuring your primer names are the same across any and all panels in which they happen to be found.</p>

<p>You should also be aware that + and - control samples will be exported from GeneMapper assuming they pass concordance control.  This is stupid, but not my fault.  So, once you have converted your files, you should remove these.  </p>

<p>Finally, GMCONVERT does not count samples with GQ scores &lt; 0.75.  Typically, these should not be used in analysis.  If you manually edit allele calls, your GQ score should be set to 1.0 (this occurs automatically).  If there is interest, I may add an option to include calls of lesser quality in a subsequent release.</p>

<h2 id="platforms">Platforms</h2>

<p>I have tested the binary, executable versions of GMCONVERT on the following platforms:</p>

<ol>
<li>Apple OS X (10.4.4) - all worked well.</li>
<li>Windows XP, SP2 - all worked well.</li>
</ol>

<p>I have tested GMCONVERT_command on the following platforms.  Helpful notes from my trials are included:</p>

<ol>
<li>Apple OS X (10.4.4), Python 2.3.5 - worked as advertised.</li>
<li>Windows XP, Python 2.4.2 - worked as advertised.</li>
<li>FreeBSD 5.4, Python 2.3.5 - works, but had invoke python with the following: /usr/local/bin/python2.3. <br />
You could change shebang or symlink /usr/local/bin/python2.3 to /usr/bin/python.  If you are using FreeBSD, you should 
know what I'm talking about.</li>
<li>Gentoo Linux (2.6.14), Python 2.4.2 - worked as advertised.</li>
</ol>

<h2 id="about_the_files_in_the_archive">About the files in the archive</h2>

<h3 id="os_x_gui">OS X - GUI</h3>

<p>Distributed as a disk-image (.dmg) file:</p>

<ul>
<li>gmconvert.app (executable)</li>
<li>gmconvert_command.py (command line version)</li>
<li>gmconvert_source.py (source code for GUI version)</li>
<li>gpl.txt (a copy of the GNU Public License)</li>
<li>NO_WARRANTY - just what it says</li>
<li>README.html - this file</li>
<li>CHANGELOG.html</li>
<li>test_data.txt - data file for testing</li>
</ul>

<h3 id="windows_gui">Windows - GUI</h3>

<p>Distributed as a Zip (.zip) file:</p>

<ul>
<li>gmconvert.exe (executable)</li>
<li>gmconvert_command.py - command line version</li>
<li>gmconvert_source.py (source code for GUI version)</li>
<li>gpl.txt (a copy of the GNU Public License)</li>
<li>NO_WARRANTY - just what it says</li>
<li>README (this file)</li>
<li>CHANGELOG.html</li>
<li>test_data.txt - data file for testing</li>
</ul>

<h3 id="gmconvert_command">GMCONVERT_command</h3>

<p>Distributed as a gzipped, tar archive (.tar.gz):</p>

<ul>
<li>gmconvert_command.py (a command line version of MicrosatFinder for use on other OSs)</li>
<li>gmconvert_source.py (source code for GUI version; requires Python and wxPython)</li>
<li>gpl.txt (a copy of the GNU Public License)</li>
<li>NO_WARRANTY - just what it says</li>
<li>README (this file)</li>
<li>CHANGELOG.html</li>
<li>test_data.txt - data file for testing</li>
</ul>

<h2 id="installing">Installing</h2>

<h3 id="gui_version_os_x">GUI Version - OS X</h3>

<ol>
<li>Double click the .dmg to mount, drag gmconvert.app to a location on your hard drive (e.g. your Applications folder)</li>
<li>Double-click to run</li>
<li>Follow the instructions</li>
</ol>

<h3 id="gui_version_windows_xp">GUI Version - Windows XP</h3>

<ol>
<li>Unzip the .zip file</li>
<li>Save the unzipped folder somewhere - DO NOT separate the contents of the unzipped folder!  This will render the program non-functional.</li>
<li>Double-click 'gmc' icon to run</li>
<li>Follow the instructions</li>
</ol>

<h3 id="command_line_version">Command-line version</h3>

<h4 id="os_x">OS X</h4>

<ol>
<li>Double click the program to unzip</li>
<li>Leave the file (gmconvert_command.py) in the directory it created or move it wherever you like.</li>
<li>Invoke the program by navigating to the folder in your command-line program of choice (e.g. terminal) 
and run it with (at minimum):</li>
</ol>

<p><code>$python gmconvert_command.py</code></p>

<p>This should give you several prompts at which you can enter paths, options, etc.</p>

<p>You may also run the program by invoking command-line options:</p>

<ul>
<li>-i [file_of sequences]</li>
<li>-f [format of outfile]</li>
<li>-o [output file location]</li>
<li>-h [shows command-line options and an example]  </li>
</ul>

<p>where -f <options> = 'cervus' | 'genepop' | 'gerud'</p>

<p>Therefore, the program can be run as such:</p>

<p><code>./gmconvert_command.py -i /Users/bcf/15_good_samples_3OLG_ls.txt -o /users/bcf/desktop/test5.csv -f gerud</code></p>

<h4 id="windows">Windows</h4>

<p>Before using the program on windows, you will need to install Python.  The current version is 2.4.2 and is available from <a href="http://www.python.org">python.org</a></p>

<h5 id="command_line_version_windows_xp_sp2_instructions_easy_way">Command-line version - Windows XP (SP2) Instructions - Easy way</h5>

<ol>
<li>Download the ZIP archive (WinZIP should also extract the .tgz archive)</li>
<li>Right-click and choose to 'Extract All...' to some folder (e.g. desktop)</li>
<li>Drag your Genemapper output to this folder</li>
<li>Double click on gmconvert_command.py</li>
<li>Hit enter @ the first prompt</li>
<li>Type the name of the file you dragged to the folder at the next prompt (don't forget to add .txt)
(e.g. if the file you dragged was Coelacanth_genotypes.txt, enter 'Coelacanth_genotypes.txt')</li>
<li>Choose an output format (cervus | genepop | gerud)</li>
<li>Hit enter at the next prompt to save the outfile with the default name in the GMCONVERT folder       </li>
</ol>

<h5 id="command_line_version_windows_xp_sp2_instructions_complicated_way">Command-line version - Windows XP (SP2) Instructions - Complicated way</h5>

<ol>
<li>Download the ZIP archive (WinZIP should also extract the .tgz archive)</li>
<li>Right-click and choose to 'Extract All...' to some location (e.g. desktop)</li>
<li>Drag gmconvert_command to some folder (e.g. c:\GeneMapper\)</li>
<li>Double click on gmconvert_command</li>
<li>Hit enter at the first prompt</li>
<li>Enter the path to your input file.  Python deals with Windows directories strangely, so you will have to enter the path.  Use forward slashes and don't forget the 'txt' 
<code>c:/myFolder/myGeneMapperExportFile.txt</code> </li>
<li>Choose a format for the output.</li>
<li>You can hit enter here to save in the current directory (in this example, it would be c:\GeneMapper) or you can save in another directory (with a different file name by entering)</li>
</ol>

<p><code>c:/myOtherFolder/myGMCONVERTOutfile.csv (or .txt or nothing for genepop)</code></p>

<p><strong>Note</strong>:  Python on windows appears to deal with spaces in directory names effectively.  So if your input file is in:
<code>c:\Documents and Settings\bcf\GeneMapper\output.txt</code></p>

<p>You would enter this upon running the program as
<code>c:/Documents and Settings/bcf/GeneMapper/output.txt (e.g. change backslashes to forward slashes)</code></p>

<h2 id="why_are_there_2_versions">Why are there 2 versions?</h2>

<p>There are 2 versions for several reasons.  There is a GUI version for OS X and Windows because it is easy to use.  There is a command-line version because it can be used for batch-processing of numerous file given a little python or shell-scripting magic (this is up to you).  The command-line version will also run on numerous platforms for which I don't have time to create a GUI.</p>

<h2 id="why_only_3_file_format_options">Why only 3 file format options?</h2>

<p>Well, because I am lazy.  Seriously, cervus, genepop, and gerud ought to cover a lot of actual programs since many do cross-conversion of files from one type to another these days.  If there is something that you absolutely must have, let me know and I will add it to the list.</p>

<h2 id="what_sort_of_license_does_this_program_have">What sort of license does this program have?</h2>

<p>This program is released under the GPL (Gnu Public License).  Details are included in gpl.txt.  Assuming you leave everything in its default directory, you may also see the license terms by typing 'GPL' after running GMCONVERT_cl.py.  This program is also released with NO WARRANTY.  Use it at your own risk (like swimming at the beach).</p>

<h2 id="technical_details">Technical details</h2>

<p>The actual script was created using <a href="http://www.python.org">python</a>, the windowing system uses <a href="http://www.wxpython.org/">wxPython</a>, the application bundles were built with <a href="http://undefined.org/python/py2app.html">py2app</a> (OS X) or <a href="http://www.py2exe.org/">py2exe</a> (Windows), the icons were made in <a href="http://www.adobe.com/creativesuite/main.html">Photoshop</a>, the .dmg file for OS X was created using <a href="http://c-command.com/dropdmg/">DropDMG</a>, and the Zip file for Windows was created on XP.</p>

<p>Bobwhite!
3/3/2005</p>

</body>
</html>